devfandomcom-20200223-history
Less
This page documents version 2 of the related code. If you are still using version 1, it is advised to update to the newer version as soon as possible. For documentation on version 1, see here (no longer updated). (incomplete) (incomplete) }} Wiki stylesheets can fast become too large to easily maintain. They can contain anything and everything from skin customisations to template styles to username highlights. In Oasis this is worsened as there is just one stylesheet by default, as opposed the normal two used in every other MediaWiki skin. This script seeks to make your wiki's CSS that little bit easier to maintain. [[wikipedia:LESS|'LESS']] is a dynamic stylesheet language. Its many features, such as variables, mixins and nesting, exist to make your CSS easier to maintain. With it you can make your stylesheets shorter, easier to follow and easier to maintain. It's very similar to the Sass stylesheets used by Wikia themselves, but LESS allows us to compile the stylesheet with javascript making this script possible. Installing Add the following to your wiki's importArticles array: importArticles( { type: 'script', articles: [ // ... 'u:dev:Less/code.2.js', //... ] } ); You will also need to configure the installation. The configuration code must come before your importArticles statement. // our config is stored in an array window.lessOpts = window.lessOpts || []; // each target page needs separate configuration window.lessOpts.push( { // this is the page that has the compiled CSS target: 'MediaWiki:Common.css', // this is the page that lists the LESS files to compile source: 'MediaWiki:Common.less', // these are the pages that you want to be able to update the target page from // note, you should not have more than one update button per page load: [ 'MediaWiki:Common.css', 'MediaWiki:Common.less' ], // this is the page that contains the comment header for the target page // all other comments are stripped during compilation header: 'MediaWiki:Css-header/common' } ); You can also add some extra optional configuration that will be shared across every target page. Again, this must come before your importArticles statement window.lessConfig = { // reloads the page after the target page has successfully been updated // defaults to true reload: true, // wraps the parsed CSS in pre tags to prevent any unwanted links to templates, pages or files // defaults to true wrap: true, // for adding non-standard usergroups that can edit the mediawiki namespace // normally this is limited to staff, vstf, helpers and sysops/admins // but if there are other groups that can edit the namespace on your wiki // add them to the array here for the script to load for them allowed: [] }; If you want to use the defaults simply remove this optional configuration, or the option you don't want to change if you only want to change part of it. For help with importArticles() see the below: Setup Firstly, you need to create the pages referenced in your configuration: target and source. As an example, MediaWiki:Common.css is our target page, which will be updated with the parsed LESS, and MediaWiki:Common.less is our source page, which contains the LESS to parse. One of the best features of Less is that it allows you to split up a large CSS file into several smaller, more easily maintainable files. To take advantage of this, we might set up our source file to look something like this: // /** * The is the root LESS file for MediaWiki:Common.css * * To update MediaWiki:Common.css from this file: * - For Oasis users: Click the "Update CSS" button at the top of the page * - For Monobook users: Click the "Update CSS" link in your toolbox */ // directory, used in imports @dir: 'MediaWiki:Common.less/'; // template styling @import '@{dir}navbox.less'; @import '@{dir}forum.less'; @import '@{dir}messagebox.less'; @import '@{dir}infobox.less'; // page specific styling @import '@{dir}mainpage.less'; // customisations @import '@{dir}webfonts.less'; // As you can see the example source page here is really a series of imports referencing a number of other LESS files found on subpages of our source page. This setup isn't required, but may help keep your CSS more manageable. If you want, you don't have to use imports and can keep all your LESS in the source page. Note, the imports, source and target page must be on the same wiki—you can't import CSS from other wikis, although it may be supported in the future. Next, you can create a page which will be added to the compiled CSS page as a header comment. This is optional, but if you do not use it, you must remove the option from your configuration; if it is in your configuration but the page does not exist, it will cause an error. This is the only comment that will be found on the page, as the comments on the original files are very unlikely to match up to the compiled CSS and are thus removed to reduce confusion. The page should be a CSS comment, such as: /** * This is the header for MediaWiki:Common.css * * This page is compiled from LESS files listed in MediaWiki:Common.less and should not be edited directly. * For documentation, see Project:CSS */ Lastly, we need to check our load array, set in the configuration. Note, this will not load on a source or target page automatically so you will need to explicitly declare the pages you want an update button on. If your source page is a series of imports, you might want to set it to load on the imported pages as well, so when you are finished editing them you can simply update the page they're used on with a single click. The main configuration is an array, meaning you can have multiple source and target pairs, say MediaWiki:Common.css and MediaWiki:Common.less, MediaWiki:Wikia.css and MediaWiki:Wikia.less, etc. However, make sure pages in the load array are only used once as only one button will load regardless of how many times it's referenced. This is because of the generic nature of the text on the update button. More than one update button per page may be supported in the future. Usage After you've set everything up, you're now ready to start using the script! To start, navigate to any page you've set to load the update CSS button on. If you're using Oasis, you'll see a button labelled "Update CSS" near the edit button. If you're a Monobook user, the update button can be found in your toolbox. If the button isn't appearing, check your configuration. After clicking the button an interface will popup. This will keep you updated on how the updating is going and notify you of most errors encountered. If it discovers a page that doesn't exist or encounters an error when parsing the content of your LESS files, it will output the error and a link to the problem page. On rare occasions, the update process will stop and no error will be output to the interface. Firstly, try reloading the page and trying again. If you have this problem repeatedly, please report the page(s) you see it on and how far into the update process you get on the talk page. Extra features * Standard mixins, documented at Less/mixins * Theme designer values ** @theme-body which corresponds to the colour of the wiki's background (behind any background image) ** @theme-buttons which corresponds to the background colour of the wiki's buttons and local wiki navigation ** @theme-header which corresponds to the background colour of the wiki's global navigation and collapsible footer bar ** @theme-links which corresponds the the colour or the links on the wiki * Formats indentation and newlines in the resulting CSS for consistency FAQ ; Do I need to learn LESS to use this script? * No! Valid CSS is valid LESS. If you don't want to use LESS for whatever reason, you can use this to split up your CSS files as well. ; Where can I learn LESS? * A guide to LESS can be found here. Translations You can help with the translation of this script! The messages that need to be translated are: * Update CSS * LESS Interface * Close * Debug mode enabled * Getting source file: $1 ** Where $1 is the source LESS file provided in the configuration * Getting standard mixins * Attempting to parse LESS * Imported $1 successfully ** Where $1 is the LESS file that was imported * Failed to import $1 ** Where $1 is the LESS file that could not be imported * Formatting CSS * Getting header comment * Successfully updated $1 ** Where $1 is the target CSS page provided in the configuration * Updating CSS from $1 ** Where $1 is the source LESS file provided the the configuration * Internal error * Page not found, please check your configuration * One or more files could not be imported, please ensure all @import statements reference existing pages * Parse error on line $1 in $2 ** Where $1 is the line number where the error was found ** Where $2 is a link to the file where the error was detected * An unknown error has occurred * If this error persists, please report it here ** Where $1 is a link to Talk:Less Please post any translations on the talk page using the following template, replacing en with your language code (or your language name if you're unsure what the code is): en: { 'update-css': 'Update CSS', 'less-title': 'LESS Interface', 'less-close': 'Close', 'debug-enabled': 'Debug mode enabled', 'getting-source': 'Getting source file: $1', 'getting-mixins': 'Getting standard mixins', 'attempt-parse': 'Attempting to parse LESS', 'import-success': 'Imported $1 successfully', 'import-error': 'Failed to import $1', 'formatting-css': 'Formatting CSS', 'edit-success': 'Successfully updated $1', 'edit-summary': 'Updating CSS from $1', 'internal-error': 'Internal error', 'page-not-found': 'Page not found, please check your configuration', 'check-imports': 'One or more files could not be imported, please ensure all @import statements reference existing pages', 'parse-error-file': 'Parse error on line $1 in $2', 'unknown-error': 'An unknown error has occurred', 'error-persist': 'If this error persists, please report it here' } You can also find additional message documentation in the source code. Updates This only documents major updates, so may not correlate with the latest update in the infobox. ; 31st July 2014 (diff) * Fixed various problems with error reporting ; 23rd July 2014 * Version 2 released ** Adds support for importing LESS files with @import ** Reworked i18n support ** Added standard mixins ** Added some theme designer values for use in stylesheets ** Added the option to wrap the CSS in pre tags ; 29th March 2014 * Script released. @import behaviour The following is notes on what less.js does when it encounters various @import statements // doesn't attempt to import // won't work through normal css @import due to lack of action=raw&ctype=text/css @import url( 'MediaWiki:Foo.css' ); @import url( '/wiki/MediaWiki:Foo.css' ); @import url( 'http://dev.wikia.com/wiki/MediaWiki:Foo.css' ); @import url( 'http://dev.wikia.com/index.php?title=MediaWiki:Foo.css' ); // doesn't attempt to import // will work through normal css @import @import url( '/wiki/MediaWiki:Foo.css?action=raw&ctype=text/css' ); @import url( '/index.php?title=MediaWiki:Foo.css&action=raw&ctype=text/css' ); @import url( 'http://dev.wikia.com/wiki/MediaWiki:Foo.css?action=raw&ctype=text/css' ); @import url( 'http://dev.wikia.com/index.php?title=MediaWiki:Foo.css&action=raw&ctype=text/css' ); // attempts to import @import url( '/load.php?debug=false&lang=en&mode=articles&articles=MediaWiki:Foo.css&only=styles' ); // attempts to import // import url -> http://dev.wikia.com/wiki/PAGENAME // less.js has been altered to append ?action=raw&ctype=text/css @import url( 'MediaWiki:Bar' ); @import url( 'MediaWiki:Common.css/bar' ); // attempts to import // import url -> /wiki/PAGENAME // less.js has been altered to append ?action=raw&ctype=text/css @import url( '/wiki/MediaWiki:Common.css/foo' ); // attempts to import // less.js has been altered to append ?action=raw&ctype=text/css @import 'MediaWiki:Bar.less'; // attempts to import // less.js has been altered to append ?action=raw&ctype=text/css @import url( 'http://dev.wikia.com/wiki/MediaWiki:Foo' ); // attempts to import // won't currently import due to it being a cross-origin request // UI doesn't react when it encounters this error, it just stops with no explanation why @import url( 'http://camtest.wikia.com/wiki/MediaWiki:Foo' )' Known bugs :No currently known bugs Planned future updates : These may be subject to change and have no release schedule associated with them. If you would like to request something that isn't listed here, please do so on the talk page. * Add support for importing LESS files from other Wikia wikis. Importing files from other MediaWiki installations, e.g. https://www.mediawiki.org, is not planned. ** Syntax might be something like u:dev:PAGENAME.less which is converted to a proper URL before importing. * Add more standard mixins similar to those used by Wikia for things like button color gradients, etc. * Add other theme-designer values * Add support for more than one update CSS button per page * Integrate the ace editor for syntax highlighting and linting as you type, similar to the codeeditor extension found on Wikimedia wikis ** Source code found at github:ajaxorg/ace, with LESS support at 1 and 2.